
<!DOCTYPE html>

<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta charset="utf-8" />
    <title>Ambient Module Users Guide &#8212; Texas A&amp;M Oil spill / Outfall Calculator 2.1.0 documentation</title>
    <link rel="stylesheet" href="../_static/alabaster.css" type="text/css" />
    <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
    <script id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
    <script src="../_static/jquery.js"></script>
    <script src="../_static/underscore.js"></script>
    <script src="../_static/doctools.js"></script>
    <script src="../_static/language_data.js"></script>
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="next" title="profile_from_ctd" href="../scripts/ambient/profile_from_ctd.html" />
    <link rel="prev" title="TAMOC User Manual" href="../user_manual.html" />
   
  <link rel="stylesheet" href="../_static/custom.css" type="text/css" />
  
  
  <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />

  </head><body>
  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          

          <div class="body" role="main">
            
  <div class="section" id="ambient-module-users-guide">
<h1>Ambient Module Users Guide<a class="headerlink" href="#ambient-module-users-guide" title="Permalink to this headline">¶</a></h1>
<dl class="field-list simple">
<dt class="field-odd">Release</dt>
<dd class="field-odd"><p>2.1</p>
</dd>
<dt class="field-even">Date</dt>
<dd class="field-even"><p>Jun 05, 2020</p>
</dd>
</dl>
<div class="section" id="scripts">
<h2>Scripts<a class="headerlink" href="#scripts" title="Permalink to this headline">¶</a></h2>
<p>A lot of the work to generate ambient CTD data and to put it into the
appropriate format for use by <code class="docutils literal notranslate"><span class="pre">TAMOC</span></code> is a ‘hands on’ process that is unique to
each project. Many times, this work can be easily completed in an IPython
interactive session using the tools supplied in this package.</p>
<p>When many profiles of a similar format need to be processed, script files that
iterate through these methods should be used. Sample scripts demonstrating use
of the classes, methods, and functions in the <cite>ambient</cite> module are provided
in the <code class="docutils literal notranslate"><span class="pre">./bin</span></code> directory of the distribution, and are summarized in the
following.</p>
<div class="toctree-wrapper compound">
<ul>
<li class="toctree-l1"><a class="reference internal" href="../scripts/ambient/profile_from_ctd.html">profile_from_ctd</a></li>
<li class="toctree-l1"><a class="reference internal" href="../scripts/ambient/profile_from_txt.html">profile_from_txt</a></li>
<li class="toctree-l1"><a class="reference internal" href="../scripts/ambient/profile_from_lab.html">profile_from_lab</a></li>
<li class="toctree-l1"><a class="reference internal" href="../scripts/ambient/profile_from_roms.html">profile_from_roms</a></li>
<li class="toctree-l1"><a class="reference internal" href="../scripts/ambient/profile_extending.html">profile_extending</a></li>
<li class="toctree-l1"><a class="reference internal" href="../scripts/ambient/profile_append.html">profile_append</a></li>
</ul>
</div>
</div>
<div class="section" id="examples">
<h2>Examples<a class="headerlink" href="#examples" title="Permalink to this headline">¶</a></h2>
<p>In each of these examples, the general process follows a similar sequence of
steps. Here we demonstrate working with CTD data following some of the steps
in the <cite>profile_from_ctd</cite> script given above.</p>
<div class="section" id="reading-in-ambient-data-files">
<h3>Reading in Ambient Data Files<a class="headerlink" href="#reading-in-ambient-data-files" title="Permalink to this headline">¶</a></h3>
<p>Read in some (or all) of the data. The first step will be to prepare a
<cite>numpy.ndarray</cite> of data that includes the depths coordinate. For this
example, we read in selected columns from <code class="docutils literal notranslate"><span class="pre">./data/ctd_BM54.cnv</span></code>. We selected
these columns by reading the <code class="docutils literal notranslate"><span class="pre">.cnv</span></code> file by hand. After changing
directory to the <code class="docutils literal notranslate"><span class="pre">./data/</span></code> directory, we start an IPython session:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">cols</span> <span class="o">=</span> <span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="mi">8</span><span class="p">,</span> <span class="mi">9</span><span class="p">,</span> <span class="mi">10</span><span class="p">,</span> <span class="mi">12</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">raw</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">loadtxt</span><span class="p">(</span><span class="s1">&#39;ctd_BM54.cnv&#39;</span><span class="p">,</span> <span class="n">skiprows</span> <span class="o">=</span> <span class="mi">175</span><span class="p">,</span> <span class="n">usecols</span> <span class="o">=</span> <span class="n">cols</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">symbols</span> <span class="o">=</span> <span class="p">[</span><span class="s1">&#39;temperature&#39;</span><span class="p">,</span> <span class="s1">&#39;pressure&#39;</span><span class="p">,</span> <span class="s1">&#39;wetlab_fluorescence&#39;</span><span class="p">,</span> <span class="s1">&#39;z&#39;</span><span class="p">,</span>
<span class="go">               &#39;salinity&#39;, &#39;density&#39;, &#39;oxygen&#39;]</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">units</span> <span class="o">=</span> <span class="p">[</span><span class="s1">&#39;deg C&#39;</span><span class="p">,</span> <span class="s1">&#39;db&#39;</span><span class="p">,</span> <span class="s1">&#39;mg/m^3&#39;</span><span class="p">,</span> <span class="s1">&#39;m&#39;</span><span class="p">,</span> <span class="s1">&#39;psu&#39;</span><span class="p">,</span> <span class="s1">&#39;kg/m^3&#39;</span><span class="p">,</span> <span class="s1">&#39;mg/l&#39;</span><span class="p">]</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">z_col</span> <span class="o">=</span> <span class="mi">3</span>
</pre></div>
</div>
<p>Many times, the raw CTD profile will contain information at the top or the
bottom of the profile that must be discarded, typically indicated by
reversals in the depth profile.  It is particularly important to remove
these reversals so that the interpolation methods will be able to find
unique profiles values for any input depth:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">ambient</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">data</span> <span class="o">=</span> <span class="n">ambient</span><span class="o">.</span><span class="n">extract_profile</span><span class="p">(</span><span class="n">raw</span><span class="p">,</span> <span class="n">z_col</span><span class="p">,</span> <span class="n">z_start</span> <span class="o">=</span> <span class="mf">50.0</span><span class="p">)</span>
</pre></div>
</div>
<p>Before the data should be stored in the netCDF dataset used by TAMOC, the
units should be converted to the standard mks system:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">profile</span><span class="p">,</span> <span class="n">units</span> <span class="o">=</span> <span class="n">ambient</span><span class="o">.</span><span class="n">convert_units</span><span class="p">(</span><span class="n">data</span><span class="p">,</span> <span class="n">units</span><span class="p">)</span>
</pre></div>
</div>
</div>
<div class="section" id="preparing-the-netcdf-dataset">
<h3>Preparing the netCDF Dataset<a class="headerlink" href="#preparing-the-netcdf-dataset" title="Permalink to this headline">¶</a></h3>
<p>An empty netCDF dataset must be created with the global metadata describing
this ambient profile before the data can be imported into the dataset:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">summary</span> <span class="o">=</span> <span class="s1">&#39;Description of the TAMOC project using this data&#39;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">source</span> <span class="o">=</span> <span class="s1">&#39;Documentation of the data source&#39;</span>
</pre></div>
</div>
<p>This next set of information is read manually by the user from the header
file of the CTD text file and entered as follows:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">sea_name</span> <span class="o">=</span> <span class="s1">&#39;Gulf of Mexico&#39;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">lat</span> <span class="o">=</span> <span class="mf">28.0</span> <span class="o">+</span> <span class="mf">43.945</span> <span class="o">/</span> <span class="mf">60.0</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">lon</span> <span class="o">=</span> <span class="mi">360</span> <span class="o">-</span> <span class="p">(</span><span class="mf">88.0</span> <span class="o">+</span> <span class="mf">22.607</span> <span class="o">/</span> <span class="mf">60.0</span><span class="p">)</span>
</pre></div>
</div>
<p>Finally, we must set the time that the CTD data were collected.  This is
done using several data manipulation methods:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">datetime</span> <span class="kn">import</span> <span class="n">datetime</span>
<span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">netCDF4</span> <span class="kn">import</span> <span class="n">num2date</span><span class="p">,</span> <span class="n">date2num</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">date</span> <span class="o">=</span> <span class="n">datetime</span><span class="p">(</span><span class="mi">2010</span><span class="p">,</span> <span class="mi">5</span><span class="p">,</span> <span class="mi">30</span><span class="p">,</span> <span class="mi">18</span><span class="p">,</span> <span class="mi">22</span><span class="p">,</span> <span class="mi">12</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">t_units</span> <span class="o">=</span> <span class="s1">&#39;seconds since 1970-01-01 00:00:00 0:00&#39;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">calendar</span> <span class="o">=</span> <span class="s1">&#39;julian&#39;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">time</span> <span class="o">=</span> <span class="n">date2num</span><span class="p">(</span><span class="n">date</span><span class="p">,</span> <span class="n">units</span><span class="o">=</span><span class="n">t_units</span><span class="p">,</span> <span class="n">calendar</span><span class="o">=</span><span class="n">calendar</span><span class="p">)</span>
</pre></div>
</div>
<p>Create the empty dataset:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">nc</span> <span class="o">=</span> <span class="n">ambient</span><span class="o">.</span><span class="n">create_nc_db</span><span class="p">(</span><span class="s1">&#39;../Profiles/BM54.nc&#39;</span><span class="p">,</span> <span class="n">summary</span><span class="p">,</span> <span class="n">source</span><span class="p">,</span> \
<span class="go">                              sea_name, lat, lon, time)</span>
</pre></div>
</div>
</div>
<div class="section" id="adding-data-to-the-netcdf-dataset">
<h3>Adding Data to the netCDF Dataset<a class="headerlink" href="#adding-data-to-the-netcdf-dataset" title="Permalink to this headline">¶</a></h3>
<p>Insert the CTD data and the associated comments into the netCDF dataset:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">comments</span> <span class="o">=</span> <span class="p">[</span><span class="s1">&#39;measured&#39;</span><span class="p">]</span> <span class="o">*</span> <span class="nb">len</span><span class="p">(</span><span class="n">symbols</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">nc</span> <span class="o">=</span> <span class="n">ambient</span><span class="o">.</span><span class="n">fill_nc_db</span><span class="p">(</span><span class="n">nc</span><span class="p">,</span> <span class="n">profile</span><span class="p">,</span> <span class="n">symbols</span><span class="p">,</span> <span class="n">units</span><span class="p">,</span> <span class="n">comments</span><span class="p">,</span> <span class="n">z_col</span><span class="p">)</span>
</pre></div>
</div>
<p>At this point the CTD data are now in a netCDF dataset with the correct
units and including all data needed by TAMOC.  If the data had originated
in netCDF format, the process could have started here.  To demonstrate
methods to work with netCDF data, we close this file and then continue our
session using the stored netCDF profile data.</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">nc</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>   <span class="c1"># This is the end of the preprocessing stage</span>
</pre></div>
</div>
</div>
<div class="section" id="using-the-ambient-profile-object">
<h3>Using the <cite>ambient.Profile</cite> Object<a class="headerlink" href="#using-the-ambient-profile-object" title="Permalink to this headline">¶</a></h3>
<p>A profile object can be initialized either by passing the file-name of the
netCDF dataset or by passing the <cite>netCDF4.Dataset</cite> object itself.  If the
variable names in the dataset match those used by <code class="docutils literal notranslate"><span class="pre">TAMOC</span></code>, the
<cite>ambient.Profile</cite> class instantiation can extract all the information itself:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">ctd_auto</span> <span class="o">=</span> <span class="n">ambient</span><span class="o">.</span><span class="n">Profile</span><span class="p">(</span><span class="s1">&#39;../test/output/BM54.nc&#39;</span><span class="p">,</span> <span class="n">chem_names</span><span class="o">=</span><span class="s1">&#39;all&#39;</span><span class="p">)</span>
</pre></div>
</div>
<p>If you want to specify the variable names for z, T, S, and P, and also
for the chemicals to load, that may also be done:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">ztsp</span> <span class="o">=</span> <span class="p">[</span><span class="s1">&#39;z&#39;</span><span class="p">,</span> <span class="s1">&#39;temperature&#39;</span><span class="p">,</span> <span class="s1">&#39;salinity&#39;</span><span class="p">,</span> <span class="s1">&#39;pressure&#39;</span><span class="p">]</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">chem_names</span> <span class="o">=</span> <span class="p">[</span><span class="s1">&#39;oxygen&#39;</span><span class="p">]</span>   <span class="c1"># This selects a subset of available data</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">ctd_manual</span> <span class="o">=</span> <span class="n">ambient</span><span class="o">.</span><span class="n">Profile</span><span class="p">(</span><span class="s1">&#39;../test/output/BM54.nc&#39;</span><span class="p">,</span> <span class="n">ztsp</span><span class="p">,</span> <span class="n">chem_names</span><span class="p">)</span>
</pre></div>
</div>
<p>If you prefer to open the netCDF file and pass the <cite>netCDF4.Dataset</cite> object,
that works identically:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">netCDF4</span> <span class="kn">import</span> <span class="n">Dataset</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">nc</span> <span class="o">=</span> <span class="n">Dataset</span><span class="p">(</span><span class="s1">&#39;../Profiles/BM54.nc&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">ctd_from_nc</span> <span class="o">=</span> <span class="n">ambient</span><span class="o">.</span><span class="n">Profile</span><span class="p">(</span><span class="n">nc</span><span class="p">)</span>  <span class="c1"># This will not load any chemicals</span>
</pre></div>
</div>
<p>Occasionally, it is necessary simulate a problem nearby, where the depth is
somewhat deeper than that in the measured profile, or in another region,
where data are not available.  The <cite>ambient.Profile</cite> object provides a method
to extend the profile to a deeper total depth while maintaining the
stratification profile:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">ctd_auto</span><span class="o">.</span><span class="n">extend_profile_deeper</span><span class="p">(</span><span class="mf">2500.</span><span class="p">,</span> <span class="s1">&#39;../test/output/BM54_deeper.nc&#39;</span><span class="p">)</span>
</pre></div>
</div>
<p>Pipes to the netCDF datasets should be closed before ending an interactive
or script session:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">ctd_auto</span><span class="o">.</span><span class="n">close_nc</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">ctd_manual</span><span class="o">.</span><span class="n">close_nc</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">ctd_from_nc</span><span class="o">.</span><span class="n">close_nc</span><span class="p">()</span>
</pre></div>
</div>
</div>
</div>
</div>


          </div>
          
        </div>
      </div>
      <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
        <div class="sphinxsidebarwrapper">
<h1 class="logo"><a href="../index.html">Texas A&M Oil spill / Outfall Calculator</a></h1>








<h3>Navigation</h3>
<ul class="current">
<li class="toctree-l1 current"><a class="reference internal" href="../user_manual.html">TAMOC User Manual</a></li>
<li class="toctree-l1"><a class="reference internal" href="../unit_tests.html">Unit Tests</a></li>
<li class="toctree-l1"><a class="reference internal" href="../glossary.html">Glossary</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../bugs.html">Reporting Bugs</a></li>
<li class="toctree-l1"><a class="reference internal" href="../readme.html">Read Me File</a></li>
<li class="toctree-l1"><a class="reference internal" href="../release.html">Release Notes</a></li>
<li class="toctree-l1"><a class="reference internal" href="../license.html">License</a></li>
</ul>

<div class="relations">
<h3>Related Topics</h3>
<ul>
  <li><a href="../index.html">Documentation overview</a><ul>
  <li><a href="../user_manual.html">TAMOC User Manual</a><ul>
      <li>Previous: <a href="../user_manual.html" title="previous chapter">TAMOC User Manual</a></li>
      <li>Next: <a href="../scripts/ambient/profile_from_ctd.html" title="next chapter">profile_from_ctd</a></li>
  </ul></li>
  </ul></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
  <h3 id="searchlabel">Quick search</h3>
    <div class="searchformwrapper">
    <form class="search" action="../search.html" method="get">
      <input type="text" name="q" aria-labelledby="searchlabel" />
      <input type="submit" value="Go" />
    </form>
    </div>
</div>
<script>$('#searchbox').show(0);</script>








        </div>
      </div>
      <div class="clearer"></div>
    </div>
    <div class="footer">
      &copy;2020, Scott A. Socolofsky.
      
      |
      Powered by <a href="http://sphinx-doc.org/">Sphinx 2.4.4</a>
      &amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
      
      |
      <a href="../_sources/guides/ambient.rst.txt"
          rel="nofollow">Page source</a>
    </div>

    

    
  </body>
</html>